Use case: HAL I3C controller private write

Sequence diagram

@startuml participant "Application" as App participant "I3C" as I3C App -> I3C: HAL_I3C_Init() App -> I3C: HAL_I3C_Ctrl_Config() App -> I3C: HAL_I3C_AddDescToFrame() App -> I3C: HAL_I3C_Ctrl_Transmit() / HAL_I3C_Ctrl_Transmit_IT() / HAL_I3C_Ctrl_Transmit_DMA() @enduml

Code snippet

HAL1

HAL2 

I3C_HandleTypeDef hi3c1;
I3C_CtrlConfTypeDef sCtrlConfig = {0};
I3C_XferTypeDef xferData;
I3C_PrivateTypeDef privateDesc;
I3C_CCCTypeDef cccDesc;
uint8_t ccc_buffer[4] = {0x01, 0x02, 0x03, 0x04};
uint8_t txBuffer[8] = {0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70, 0x80};
uint8_t rx_buffer[8]  = {0};
uint32_t ctrlBuffer[2] = {0};
uint32_t status_buffer[2] = {0};

// Initialize I3C peripheral
hi3c1.Instance = I3C1;
hi3c1.Mode = HAL_I3C_MODE_CONTROLLER;
hi3c1.Init.CtrlBusCharacteristic.SDAHoldTime = HAL_I3C_SDA_HOLD_TIME_1_5;
hi3c1.Init.CtrlBusCharacteristic.WaitTime = HAL_I3C_OWN_ACTIVITY_STATE_0;
hi3c1.Init.CtrlBusCharacteristic.SCLPPLowDuration = 0x7c;
hi3c1.Init.CtrlBusCharacteristic.SCLI3CHighDuration = 0x7c;
hi3c1.Init.CtrlBusCharacteristic.SCLODLowDuration = 0x7c;
hi3c1.Init.CtrlBusCharacteristic.SCLI2CHighDuration = 0x00;
hi3c1.Init.CtrlBusCharacteristic.BusFreeDuration = 0x32;
hi3c1.Init.CtrlBusCharacteristic.BusIdleDuration = 0xf8;
HAL_I3C_Init(&hi3c1);

// Configure controller
sCtrlConfig.DynamicAddr = 0;
sCtrlConfig.StallTime = 0x10;
sCtrlConfig.HotJoinAllowed = DISABLE;
sCtrlConfig.ACKStallState = DISABLE;
sCtrlConfig.CCCStallState = ENABLE;
sCtrlConfig.TxStallState = DISABLE;
sCtrlConfig.RxStallState = DISABLE;
sCtrlConfig.HighKeeperSDA = DISABLE;
HAL_I3C_Ctrl_Config(&hi3c1, &sCtrlConfig);

// Fill CCC descriptor
cccDesc.TargetAddr = 0x22;
cccDesc.CCC = 0x85;
cccDesc.CCCBuf.pBuffer = ccc_buffer;
cccDesc.CCCBuf.Size = sizeof(ccc_buffer);
cccDesc.Direction = 0;

// Fill Private descriptor
privateDesc.TargetAddr = 0x22;
privateDesc.TxBuf.pBuffer = txBuffer;
privateDesc.TxBuf.Size = sizeof(txBuffer);
privateDesc.RxBuf.pBuffer = rx_buffer;
privateDesc.RxBuf.Size = sizeof(rx_buffer);
privateDesc.Direction = 0;

// Fill transfer structure
xferData.CtrlBuf.pBuffer = ctrlBuffer;
xferData.CtrlBuf.Size = 2;
xferData.StatusBuf.pBuffer = status_buffer;
xferData.StatusBuf.Size = 2;
xferData.TxBuf.pBuffer = txBuffer;
xferData.TxBuf.Size = sizeof(txBuffer);
xferData.RxBuf.pBuffer = rx_buffer;
xferData.RxBuf.Size = sizeof(rx_buffer);

uint8_t nbFrame = 1;
uint32_t option = 0;

// Add descriptors to frame
HAL_StatusTypeDef status = HAL_I3C_AddDescToFrame(
    &hi3c1,
    &cccDesc,
    &privateDesc,
    &xferData,
    nbFrame,
    option
);

// Start transfer (choose one mode)
/* Polling mode: the function returns only when the transfer is complete */
HAL_I3C_Ctrl_Transmit(&hi3c1, &xferData, 1000);
/* Interrupt and DMA modes: the operation is asynchronous and completion
will be notified to the user via HAL_I3C_CtrlTxCpltCallback */
HAL_I3C_Ctrl_Transmit_IT(&hi3c1, &xferData);
HAL_I3C_Ctrl_Transmit_DMA(&hi3c1, &xferData);

hal_i3c_handle_t hi3c1;
hal_i3c_ctrl_config_t sCtrlConfig;
hal_i3c_transfer_ctx_t xfer_ctx;
hal_i3c_ccc_desc_t ccc_desc;
uint32_t ctrl_buf[2] = {0x12345678, 0x9ABCDEF0};
uint8_t tx_buf[8] = {0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70, 0x80};
uint8_t tx_data[8] = {0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70, 0x80};















// Initialize I3C peripheral
HAL_I3C_Init(&hi3c1, HAL_I3C1);


// Configure controller
sCtrlConfig.scl_waveform = 0xFFFFFFFF;
sCtrlConfig.timing = 0xFFFFFFFF;
HAL_I3C_CTRL_SetConfig(&hi3c1, &sCtrlConfig);

// Configure stall time
HAL_I3C_CTRL_SetConfigStallTime(&hi3c1, 0x10, HAL_I3C_CTRL_STALL_CCC);

// Fill the private descriptor
hal_i3c_private_desc_t private_desc;
private_desc.tgt_addr = 0x22;
private_desc.data_size_byte = sizeof(tx_data);
private_desc.direction = HAL_I3C_DIRECTION_WRITE;

// Initialize transfer context
xfer_ctx.p_tc_data = NULL;
xfer_ctx.tc_size_word = 0;
xfer_ctx.p_tx_data = tx_data;
xfer_ctx.tx_size_byte = sizeof(tx_data);
xfer_ctx.p_rx_data = NULL;
xfer_ctx.rx_size_byte = 0;
xfer_ctx.transfer_mode = HAL_I3C_PRIVATE_WITH_ARB_RESTART;
xfer_ctx.nb_tx_frame = 1;









HAL_I3C_CTRL_InitTransferCtxTc(&xfer_ctx, ctrl_buf, 2);
HAL_I3C_CTRL_InitTransferCtxTx(&xfer_ctx, tx_buf, sizeof(tx_buf));

// Build CCC transfer context
HAL_I3C_CTRL_BuildTransferCtxPrivate(&xfer_ctx, &private_desc,
                                 1, HAL_I3C_PRIVATE_WITH_ARB_RESTART);





// Start the I3C transfer (choose one mode)
/* Polling mode: the function returns only when the transfer is complete */
HAL_I3C_CTRL_Transfer(&hi3c1, &xfer_ctx, 1000);
/* Interrupt and DMA modes: the operation is asynchronous and completion
will be notified to the user via HAL_I3C_CTRL_TransferCpltCallback */
HAL_I3C_CTRL_Transfer_IT(&hi3c1, &xfer_ctx);
HAL_I3C_CTRL_Transfer_DMA(&hi3c1, &xfer_ctx);

Key changes

  1. HAL2 applies controller configuration using HAL_I3C_CTRL_SetConfig() and configures stall time using HAL_I3C_CTRL_SetConfigStallTime().

  2. HAL2 builds a transfer context using HAL_I3C_CTRL_InitTransferCtx*() and HAL_I3C_CTRL_BuildTransferCtxPrivate().

  3. HAL2 starts the transfer using HAL_I3C_CTRL_Transfer*() instead of HAL_I3C_Ctrl_Transmit*().